home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-3 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  50KB  |  942 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: Character Type,  Next: Sequence Type,  Prev: Floating Point Type,  Up: Programming Types
  20. Character Type
  21. --------------
  22.    A "character" in Emacs Lisp is nothing more than an integer.  In
  23. other words, characters are represented by their character codes.  For
  24. example, the character `A' is represented as the integer 65.
  25.    Individual characters are not often used in programs.  It is far more
  26. common to work with *strings*, which are sequences composed of
  27. characters.  *Note String Type::.
  28.    Characters in strings, buffers, and files are currently limited to
  29. the range of 0 to 255.  If an arbitrary integer is used as a character
  30. for those purposes, only the lower eight bits are significant.
  31. Characters that represent keyboard input have a much wider range.
  32.    Since characters are really integers, the printed representation of a
  33. character is a decimal number.  This is also a possible read syntax for
  34. a character, but writing characters that way in Lisp programs is a very
  35. bad idea.  You should *always* use the special read syntax formats that
  36. Emacs Lisp provides for characters.  These syntax formats start with a
  37. question mark.
  38.    The usual read syntax for alphanumeric characters is a question mark
  39. followed by the character; thus, `?A' for the character `A', `?B' for
  40. the character `B', and `?a' for the character `a'.
  41.    For example:
  42.      ?Q => 81
  43.      
  44.      ?q => 113
  45.    You can use the same syntax for punctuation characters, but it is
  46. often a good idea to add a `\' to prevent Lisp mode from getting
  47. confused.  For example, `?\ ' is the way to write the space character.
  48. If the character is `\', you *must* use a second `\' to quote it: `?\\'.
  49.    You can express the characters control-g, backspace, tab, newline,
  50. vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
  51. `?\n', `?\v', `?\f', `?\r', `?\e', respectively.  Those values are 7,
  52. 8, 9, 10, 11, 12, 13, and 27 in decimal.  Thus,
  53.      ?\a => 7                 ; `C-g'
  54.      ?\b => 8                 ; backspace, BS, `C-h'
  55.      ?\t => 9                 ; tab, TAB, `C-i'
  56.      ?\n => 10                ; newline, LFD, `C-j'
  57.      ?\v => 11                ; vertical tab, `C-k'
  58.      ?\f => 12                ; formfeed character, `C-l'
  59.      ?\r => 13                ; carriage return, RET, `C-m'
  60.      ?\e => 27                ; escape character, ESC, `C-['
  61.      ?\\ => 92                ; backslash character, `\'
  62.    These sequences which start with backslash are also known as "escape
  63. sequences", because backslash plays the role of an escape character,
  64. but they have nothing to do with the character ESC.
  65.    Control characters may be represented using yet another read syntax.
  66. This consists of a question mark followed by a backslash, caret, and the
  67. corresponding non-control character, in either upper or lower case.  For
  68. example, either `?\^I' or `?\^i' may be used as the read syntax for the
  69. character `C-i', the character whose value is 9.
  70.    Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
  71. `?\^I' and to `?\^i':
  72.      ?\^I => 9
  73.      
  74.      ?\C-I => 9
  75.    For use in strings and buffers, you are limited to the control
  76. characters that exist in ASCII, but for keyboard input purposes, you
  77. can turn any character into a control character with `C-'.  The
  78. character codes for these characters include the 2**22 bit as well as
  79. the code for the non-control character.  Ordinary terminals have no way
  80. of generating non-ASCII control characters, but you can generate them
  81. straightforwardly using an X terminal.
  82.    The DEL key can be considered and written as `Control-?':
  83.      ?\^? => 127
  84.      
  85.      ?\C-? => 127
  86.    When you represent control characters to be found in files or
  87. strings, we recommend the `^' syntax; but when you refer to keyboard
  88. input, we prefer the `C-' syntax.  This does not affect the meaning of
  89. the program, but may guide the understanding of people who read it.
  90.    A "meta character" is a character typed with the META key.  The
  91. integer that represents such a character has the 2**23 bit set (which
  92. on most machines makes it a negative number).  We use high bits for
  93. this and other modifiers to make possible a wide range of basic
  94. character codes.
  95.    In a string, the 2**7 bit indicates a meta character, so the meta
  96. characters that can fit in a string have codes in the range from 128 to
  97. 255, and are the meta versions of the ordinary ASCII characters.  (In
  98. Emacs versions 18 and older, this convention was used for characters
  99. outside of strings as well.)
  100.    The read syntax for meta characters uses `\M-'.  For example,
  101. `?\M-A' stands for `M-A'.  You can use `\M-' together with octal codes,
  102. `\C-', or any other syntax for a character.  Thus, you can write `M-A'
  103. as `?\M-A', or as `?\M-\101'.  Likewise, you can write `C-M-b' as
  104. `?\M-\C-b', `?\C-\M-b', or `?\M-\002'.
  105.    The shift modifier is used in indicating the case of a character in
  106. special circumstances.  The case of an ordinary letter is indicated by
  107. its character code as part of ASCII, but ASCII has no way to represent
  108. whether a control character is upper case or lower case.  Emacs uses the
  109. 2**21 bit to indicate that the shift key was used for typing a control
  110. character.  This distinction is possible only when you use X terminals
  111. or other special terminals; ordinary terminals do not indicate the
  112. distinction to the computer in any way.
  113.    The X Window system defines three other modifier bits that can be set
  114. in a character: "hyper", "super" and "alt".  The syntaxes for these
  115. bits are `\H-', `\s-' and `\A-'.  Thus, `?\H-\M-\A-x' represents
  116. `Alt-Hyper-Meta-x'.  Numerically, the bit values are 2**18 for alt,
  117. 2**19 for super and 2**20 for hyper.
  118.    Finally, the most general read syntax consists of a question mark
  119. followed by a backslash and the character code in octal (up to three
  120. octal digits); thus, `?\101' for the character `A', `?\001' for the
  121. character `C-a', and `?\002' for the character `C-b'.  Although this
  122. syntax can represent any ASCII character, it is preferred only when the
  123. precise octal value is more important than the ASCII representation.
  124.      ?\012 => 10        ?\n => 10         ?\C-j => 10
  125.      
  126.      ?\101 => 65        ?A => 65
  127.    A backslash is allowed, and harmless, preceding any character without
  128. a special escape meaning; thus, `?\A' is equivalent to `?A'.  There is
  129. no reason to use a backslash before most such characters.  However, any
  130. of the characters `()\|;'`"#.,' should be preceded by a backslash to
  131. avoid confusing the Emacs commands for editing Lisp code.  Whitespace
  132. characters such as space, tab, newline and formfeed should also be
  133. preceded by a backslash.  However, it is cleaner to use one of the
  134. easily readable escape sequences, such as `\t', instead of an actual
  135. control character such as a tab.
  136. File: elisp,  Node: Sequence Type,  Next: List Type,  Prev: Character Type,  Up: Programming Types
  137. Sequence Types
  138. --------------
  139.    A "sequence" is a Lisp object that represents an ordered set of
  140. elements.  There are two kinds of sequence in Emacs Lisp, lists and
  141. arrays.  Thus, an object of type list or of type array is also
  142. considered a sequence.
  143.    Arrays are further subdivided into strings and vectors.  Vectors can
  144. hold elements of any type, but string elements must be characters in the
  145. range from 0 to 255.  However, the characters in a string can have text
  146. properties; vectors do not support text properties even when their
  147. elements happen to be characters.
  148.    Lists, strings and vectors are different, but they have important
  149. similarities.  For example, all have a length L, and all have elements
  150. which can be indexed from zero to L minus one.  Also, several
  151. functions, called sequence functions, accept any kind of sequence.  For
  152. example, the function `elt' can be used to extract an element of a
  153. sequence, given its index.  *Note Sequences Arrays Vectors::.
  154.    It is impossible to read the same sequence twice, in the sense of
  155. `eq' (*note Equality Predicates::.), since sequences are always created
  156. anew upon reading.  There is one exception: the empty list `()' always
  157. stands for the same object, `nil'.
  158. File: elisp,  Node: List Type,  Next: Array Type,  Prev: Sequence Type,  Up: Programming Types
  159. List Type
  160. ---------
  161.    A "list" is a series of cons cells, linked together.  A "cons cell"
  162. is an object comprising two pointers named the CAR and the CDR.  Each
  163. of them can point to any Lisp object, but when the cons cell is part of
  164. a list, the CDR points either to another cons cell or to the empty
  165. list.  *Note Lists::, for functions that work on lists.
  166.    The names CAR and CDR have only historical meaning now.  The
  167. original Lisp implementation ran on an IBM 704 computer which divided
  168. words into two parts, called the "address" part and the "decrement";
  169. CAR was an instruction to extract the contents of the address part of a
  170. register, and CDR an instruction to extract the contents of the
  171. decrement.  By contrast, "cons cells" are named for the function `cons'
  172. that creates them, which in turn is named for its purpose, the
  173. construction of cells.
  174.    Because cons cells are so central to Lisp, we also have a word for
  175. "an object which is not a cons cell".  These objects are called "atoms".
  176.    The read syntax and printed representation for lists are identical,
  177. and consist of a left parenthesis, an arbitrary number of elements, and
  178. a right parenthesis.
  179.    Upon reading, any object inside the parentheses is made into an
  180. element of the list.  That is, a cons cell is made for each element.
  181. The CAR of the cons cell points to the element, and its CDR points to
  182. the next cons cell which holds the next element in the list.  The CDR
  183. of the last cons cell is set to point to `nil'.
  184.    A list can be illustrated by a diagram in which the cons cells are
  185. shown as pairs of boxes.  (The Lisp reader cannot read such an
  186. illustration; unlike the textual notation, which can be understood both
  187. humans and computers, the box illustrations can only be understood by
  188. humans.)  The following represents the three-element list `(rose violet
  189. buttercup)':
  190.          ___ ___      ___ ___      ___ ___
  191.         |___|___|--> |___|___|--> |___|___|--> nil
  192.           |            |            |
  193.           |            |            |
  194.            --> rose     --> violet   --> buttercup
  195.    In the diagram, each box represents a slot that can refer to any Lisp
  196. object.  Each pair of boxes represents a cons cell.  Each arrow is a
  197. reference to a Lisp object, either an atom or another cons cell.
  198.    In this example, the first box, the CAR of the first cons cell,
  199. refers to or "contains" `rose' (a symbol).  The second box, the CDR of
  200. the first cons cell, refers to the next pair of boxes, the second cons
  201. cell.  The CAR of the second cons cell refers to `violet' and the CDR
  202. refers to the third cons cell.  The CDR of the third (and last) cons
  203. cell refers to `nil'.
  204.    Here is another diagram of the same list, `(rose violet buttercup)',
  205. sketched in a different manner:
  206.      ---------------       ----------------       -------------------
  207.      | car   | cdr   |     | car    | cdr   |     | car       | cdr   |
  208.      | rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
  209.      |       |       |     |        |       |     |           |       |
  210.       ---------------       ----------------       -------------------
  211.    A list with no elements in it is the "empty list"; it is identical
  212. to the symbol `nil'.  In other words, `nil' is both a symbol and a list.
  213.    Here are examples of lists written in Lisp syntax:
  214.      (A 2 "A")            ; A list of three elements.
  215.      ()                   ; A list of no elements (the empty list).
  216.      nil                  ; A list of no elements (the empty list).
  217.      ("A ()")             ; A list of one element: the string `"A ()"'.
  218.      (A ())               ; A list of two elements: `A' and the empty list.
  219.      (A nil)              ; Equivalent to the previous.
  220.      ((A B C))            ; A list of one element
  221.                           ;   (which is a list of three elements).
  222.    Here is the list `(A ())', or equivalently `(A nil)', depicted with
  223. boxes and arrows:
  224.          ___ ___      ___ ___
  225.         |___|___|--> |___|___|--> nil
  226.           |            |
  227.           |            |
  228.            --> A        --> nil
  229. * Menu:
  230. * Dotted Pair Notation::        An alternative syntax for lists.
  231. * Association List Type::       A specially constructed list.
  232. File: elisp,  Node: Dotted Pair Notation,  Next: Association List Type,  Up: List Type
  233. Dotted Pair Notation
  234. ....................
  235.    "Dotted pair notation" is an alternative syntax for cons cells that
  236. represents the CAR and CDR explicitly.  In this syntax, `(A . B)'
  237. stands for a cons cell whose CAR is the object A, and whose CDR is the
  238. object B.  Dotted pair notation is therefore more general than list
  239. syntax.  In the dotted pair notation, the list `(1 2 3)' is written as
  240. `(1 .  (2 . (3 . nil)))'.  For `nil'-terminated lists, the two
  241. notations produce the same result, but list notation is usually clearer
  242. and more convenient when it is applicable.  When printing a list, the
  243. dotted pair notation is only used if the CDR of a cell is not a list.
  244.    Box notation can also be used to illustrate what dotted pairs look
  245. like.  For example, `(rose . violet)' is diagrammed as follows:
  246.          ___ ___
  247.         |___|___|--> violet
  248.           |
  249.           |
  250.            --> rose
  251.    Dotted pair notation can be combined with list notation to represent
  252. a chain of cons cells with a non-`nil' final CDR.  For example, `(rose
  253. violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
  254. The object looks like this:
  255.          ___ ___      ___ ___
  256.         |___|___|--> |___|___|--> buttercup
  257.           |            |
  258.           |            |
  259.            --> rose     --> violet
  260.    These diagrams make it evident that `(rose . violet . buttercup)'
  261. must have an invalid syntax since it would require that a cons cell
  262. have three parts rather than two.
  263.    The list `(rose violet)' is equivalent to `(rose . (violet))' and
  264. looks like this:
  265.          ___ ___      ___ ___
  266.         |___|___|--> |___|___|--> nil
  267.           |            |
  268.           |            |
  269.            --> rose     --> violet
  270.    Similarly, the three-element list `(rose violet buttercup)' is
  271. equivalent to `(rose . (violet . (buttercup)))'.  It looks like this:
  272.          ___ ___      ___ ___      ___ ___
  273.         |___|___|--> |___|___|--> |___|___|--> nil
  274.           |            |            |
  275.           |            |            |
  276.            --> rose     --> violet   --> buttercup
  277. File: elisp,  Node: Association List Type,  Prev: Dotted Pair Notation,  Up: List Type
  278. Association List Type
  279. .....................
  280.    An "association list" or "alist" is a specially-constructed list
  281. whose elements are cons cells.  In each element, the CAR is considered
  282. a "key", and the CDR is considered an "associated value".  (In some
  283. cases, the associated value is stored in the CAR of the CDR.)
  284. Association lists are often used to implement stacks, since new
  285. associations may easily be added to or removed from the front of the
  286. list.
  287.    For example,
  288.      (setq alist-of-colors
  289.            '((rose . red) (lily . white)  (buttercup . yellow)))
  290. sets the variable `alist-of-colors' to an alist of three elements.  In
  291. the first element, `rose' is the key and `red' is the value.
  292.    *Note Association Lists::, for a further explanation of alists and
  293. for functions that work on alists.
  294. File: elisp,  Node: Array Type,  Next: String Type,  Prev: List Type,  Up: Programming Types
  295. Array Type
  296. ----------
  297.    An "array" is composed of an arbitrary number of other Lisp objects,
  298. arranged in a contiguous block of memory.  Any element of an array may
  299. be accessed in constant time.  In contrast, accessing an element of a
  300. list requires time proportional to the position of the element in the
  301. list.  (Elements at the end of a list take longer to access than
  302. elements at the beginning of a list.)
  303.    Emacs defines two types of array, strings and vectors.  A string is
  304. an array of characters and a vector is an array of arbitrary objects.
  305. Both are one-dimensional.  (Most other programming languages support
  306. multidimensional arrays, but we don't think they are essential in Emacs
  307. Lisp.)  Each type of array has its own read syntax; see *Note String
  308. Type::, and *Note Vector Type::.
  309.    An array may have any length up to the largest integer; but once
  310. created, it has a fixed size.  The first element of an array has index
  311. zero, the second element has index 1, and so on.  This is called
  312. "zero-origin" indexing.  For example, an array of four elements has
  313. indices 0, 1, 2, and 3.
  314.    The array type is contained in the sequence type and contains both
  315. strings and vectors.
  316. File: elisp,  Node: String Type,  Next: Vector Type,  Prev: Array Type,  Up: Programming Types
  317. String Type
  318. -----------
  319.    A "string" is an array of characters.  Strings are used for many
  320. purposes in Emacs, as can be expected in a text editor; for example, as
  321. the names of Lisp symbols, as messages for the user, and to represent
  322. text extracted from buffers.  Strings in Lisp are constants; evaluation
  323. of a string returns the same string.
  324.    The read syntax for strings is a double-quote, an arbitrary number of
  325. characters, and another double-quote, `"like this"'.  The Lisp reader
  326. accepts the same formats for reading the characters of a string as it
  327. does for reading single characters (without the question mark that
  328. begins a character literal).  You can enter a nonprinting character such
  329. as tab, `C-a' or `M-C-A' using the convenient escape sequences, like
  330. this: `"\t, \C-a, \M-\C-a"'.  You can include a double-quote in a
  331. string by preceding it with a backslash; thus, `"\""' is a string
  332. containing just a single double-quote character.  (*Note Character
  333. Type::, for a description of the read syntax for characters.)
  334.    If you use the `\M-' syntax to indicate a meta character in a string
  335. constant, this sets the 2**7 bit of the character in the string.  This
  336. is not the same representation that the meta modifier has in a
  337. character regarded as a simple integer.  *Note Character Type::.
  338.    Strings cannot hold characters that have the hyper, super or alt
  339. modifiers; they can hold ASCII control characters, but no others.  They
  340. do not distinguish case in ASCII control characters.
  341.    In contrast with the C programming language, Emacs Lisp allows
  342. newlines in string literals.  But an escaped newline--one that is
  343. preceded by `\'--does not become part of the string; i.e., the Lisp
  344. reader ignores an escaped newline in a string literal.
  345.      "It is useful to include newlines
  346.      in documentation strings,
  347.      but the newline is \
  348.      ignored if escaped."
  349.           => "It is useful to include newlines
  350.      in documentation strings,
  351.      but the newline is ignored if escaped."
  352.    The printed representation of a string consists of a double-quote,
  353. the characters it contains, and another double-quote.  However, any
  354. backslash or double-quote characters in the string are preceded with a
  355. backslash like this: `"this \" is an embedded quote"'.
  356.    A string can hold properties of the text it contains, in addition to
  357. the characters themselves.  This enables programs that copy text between
  358. strings and buffers to preserve the properties with no special effort.
  359. *Note Text Properties::.  Strings with text properties have a special
  360. read and print syntax:
  361.      #("CHARACTERS" PROPERTY-DATA...)
  362. where PROPERTY-DATA is zero or more elements in groups of three as
  363. follows:
  364.      BEG END PLIST
  365. The elements BEG and END are integers, and together specify a portion
  366. of the string; PLIST is the property list for that portion.
  367.    *Note Strings and Characters::, for functions that work on strings.
  368. File: elisp,  Node: Vector Type,  Next: Symbol Type,  Prev: String Type,  Up: Programming Types
  369. Vector Type
  370. -----------
  371.    A "vector" is a one-dimensional array of elements of any type.  It
  372. takes a constant amount of time to access any element of a vector.  (In
  373. a list, the access time of an element is proportional to the distance of
  374. the element from the beginning of the list.)
  375.    The printed representation of a vector consists of a left square
  376. bracket, the elements, and a right square bracket.  This is also the
  377. read syntax.  Like numbers and strings, vectors are considered constants
  378. for evaluation.
  379.      [1 "two" (three)]      ; A vector of three elements.
  380.           => [1 "two" (three)]
  381.    *Note Vectors::, for functions that work with vectors.
  382. File: elisp,  Node: Symbol Type,  Next: Lisp Function Type,  Prev: Vector Type,  Up: Programming Types
  383. Symbol Type
  384. -----------
  385.    A "symbol" in GNU Emacs Lisp is an object with a name.  The symbol
  386. name serves as the printed representation of the symbol.  In ordinary
  387. use, the name is unique--no two symbols have the same name.
  388.    A symbol may be used in programs as a variable, as a function name,
  389. or to hold a list of properties.  Or it may serve only to be distinct
  390. from all other Lisp objects, so that its presence in a data structure
  391. may be recognized reliably.  In a given context, usually only one of
  392. these uses is intended.
  393.    A symbol name can contain any characters whatever.  Most symbol names
  394. are written with letters, digits, and the punctuation characters
  395. `-+=*/'.  Such names require no special punctuation; the characters of
  396. the name suffice as long as the name does not look like a number.  (If
  397. it does, write a `\' at the beginning of the name to force
  398. interpretation as a symbol.)  The characters `_~!@$%^&:<>{}' are less
  399. often used but also require no special punctuation.  Any other
  400. characters may be included in a symbol's name by escaping them with a
  401. backslash.  In contrast to its use in strings, however, a backslash in
  402. the name of a symbol quotes the single character that follows the
  403. backslash, without conversion.  For example, in a string, `\t'
  404. represents a tab character; in the name of a symbol, however, `\t'
  405. merely quotes the letter `t'.  To have a symbol with a tab character in
  406. its name, you must actually type an tab (preceded with a backslash).
  407. But you would hardly ever do such a thing.
  408.      Common Lisp note: in Common Lisp, lower case letters are always
  409.      "folded" to upper case, unless they are explicitly escaped.  This
  410.      is in contrast to Emacs Lisp, in which upper case and lower case
  411.      letters are distinct.
  412.    Here are several examples of symbol names.  Note that the `+' in the
  413. fifth example is escaped to prevent it from being read as a number.
  414. This is not necessary in the last example because the rest of the name
  415. makes it invalid as a number.
  416.      foo                 ; A symbol named `foo'.
  417.      FOO                 ; A symbol named `FOO', different from `foo'.
  418.      char-to-string      ; A symbol named `char-to-string'.
  419.      1+                  ; A symbol named `1+'
  420.                          ;   (not `+1', which is an integer).
  421.      \+1                 ; A symbol named `+1'
  422.                          ;   (not a very readable name).
  423.      \(*\ 1\ 2\)         ; A symbol named `(* 1 2)' (a worse name).
  424.      +-*/_~!@$%^&=:<>{}  ; A symbol named `+-*/_~!@$%^&=:<>{}'.
  425.                          ;   These characters need not be escaped.
  426. File: elisp,  Node: Lisp Function Type,  Next: Lisp Macro Type,  Prev: Symbol Type,  Up: Programming Types
  427. Lisp Function Type
  428. ------------------
  429.    Just as functions in other programming languages are executable,
  430. "Lisp function" objects are pieces of executable code.  However,
  431. functions in Lisp are primarily Lisp objects, and only secondarily the
  432. text which represents them.  These Lisp objects are lambda expressions:
  433. lists whose first element is the symbol `lambda' (*note Lambda
  434. Expressions::.).
  435.    In most programming languages, it is impossible to have a function
  436. without a name.  In Lisp, a function has no intrinsic name.  A lambda
  437. expression is also called an "anonymous function" (*note Anonymous
  438. Functions::.).  A named function in Lisp is actually a symbol with a
  439. valid function in its function cell (*note Defining Functions::.).
  440.    Most of the time, functions are called when their names are written
  441. in Lisp expressions in Lisp programs.  However, a function object found
  442. or constructed at run time can be called and passed arguments with the
  443. primitive functions `funcall' and `apply'.  *Note Calling Functions::.
  444. File: elisp,  Node: Lisp Macro Type,  Next: Primitive Function Type,  Prev: Lisp Function Type,  Up: Programming Types
  445. Lisp Macro Type
  446. ---------------
  447.    A "Lisp macro" is a user-defined construct that extends the Lisp
  448. language.  It is represented as an object much like a function, but with
  449. different parameter-passing semantics.  A Lisp macro has the form of a
  450. list whose first element is the symbol `macro' and whose CDR is a Lisp
  451. function object, including the `lambda' symbol.
  452.    Lisp macro objects are usually defined with the built-in `defmacro'
  453. function, but any list that begins with `macro' is a macro as far as
  454. Emacs is concerned.  *Note Macros::, for an explanation of how to write
  455. a macro.
  456. File: elisp,  Node: Primitive Function Type,  Next: Byte-Code Type,  Prev: Lisp Macro Type,  Up: Programming Types
  457. Primitive Function Type
  458. -----------------------
  459.    A "primitive function" is a function callable from Lisp but written
  460. in the C programming language.  Primitive functions are also called
  461. "subrs" or "built-in functions".  (The word "subr" is derived from
  462. "subroutine".)  Most primitive functions evaluate all their arguments
  463. when they are called.  A primitive function that does not evaluate all
  464. its arguments is called a "special form" (*note Special Forms::.).
  465.    It does not matter to the caller of a function whether the function
  466. is primitive.  However, this does matter if you are trying to
  467. substitute a function written in Lisp for a primitive of the same name.
  468. The reason is that the primitive function may be called directly from
  469. C code.  When the redefined function is called from Lisp, the new
  470. definition will be used; but calls from C code may still use the old
  471. definition.
  472.    The term "function" is used to refer to all Emacs functions, whether
  473. written in Lisp or C.  *Note Lisp Function Type::, for information
  474. about the functions written in Lisp.
  475.    Primitive functions have no read syntax and print in hash notation
  476. with the name of the subroutine.
  477.      (symbol-function 'car)          ; Access the function cell
  478.                                      ;   of the symbol.
  479.           => #<subr car>
  480.      (subrp (symbol-function 'car))  ; Is this a primitive function?
  481.           => t                       ; Yes.
  482. File: elisp,  Node: Byte-Code Type,  Next: Autoload Type,  Prev: Primitive Function Type,  Up: Programming Types
  483. Byte-Code Function Type
  484. -----------------------
  485.    The byte compiler produces "byte-code function objects".
  486. Internally, a byte-code function object is much like a vector; however,
  487. the evaluator handles this data type specially when it appears as a
  488. function to be called.  *Note Byte Compilation::, for information about
  489. the byte compiler.
  490.    The printed representation for a byte-code function object is like
  491. that for a vector, with an additional `#' before the opening `['.
  492. File: elisp,  Node: Autoload Type,  Prev: Byte-Code Type,  Up: Programming Types
  493. Autoload Type
  494. -------------
  495.    An "autoload object" is a list whose first element is the symbol
  496. `autoload'.  It is stored as the function definition of a symbol to say
  497. that a file of Lisp code should be loaded when necessary to find the
  498. true definition of that symbol.  The autoload object contains the name
  499. of the file, plus some other information about the real definition.
  500.    After the file has been loaded, the symbol should have a new function
  501. definition that is not an autoload object.  The new definition is then
  502. called as if it had been there to begin with.  From the user's point of
  503. view, the function call works as expected, using the function definition
  504. in the loaded file.
  505.    An autoload object is usually created with the function `autoload',
  506. which stores the object in the function cell of a symbol.  *Note
  507. Autoload::, for more details.
  508. File: elisp,  Node: Editing Types,  Next: Type Predicates,  Prev: Programming Types,  Up: Types of Lisp Object
  509. Editing Types
  510. =============
  511.    The types in the previous section are common to many Lisp-like
  512. languages.  But Emacs Lisp provides several additional data types for
  513. purposes connected with editing.
  514. * Menu:
  515. * Buffer Type::         The basic object of editing.
  516. * Window Type::         Buffers are displayed in windows.
  517. * Frame Type::        Windows subdivide frames.
  518. * Window Configuration Type::   Recording the way a frame is subdivided.
  519. * Marker Type::         A position in a buffer.
  520. * Process Type::        A process running on the underlying OS.
  521. * Stream Type::         Receive or send characters.
  522. * Keymap Type::         What function a keystroke invokes.
  523. * Syntax Table Type::   What a character means.
  524. * Display Table Type::  How display tables are represented.
  525. * Overlay Type::        How an overlay is represented.
  526. File: elisp,  Node: Buffer Type,  Next: Window Type,  Up: Editing Types
  527. Buffer Type
  528. -----------
  529.    A "buffer" is an object that holds text that can be edited (*note
  530. Buffers::.).  Most buffers hold the contents of a disk file (*note
  531. Files::.) so they can be edited, but some are used for other purposes.
  532. Most buffers are also meant to be seen by the user, and therefore
  533. displayed, at some time, in a window (*note Windows::.).  But a buffer
  534. need not be displayed in a window.
  535.    The contents of a buffer are much like a string, but buffers are not
  536. used like strings in Emacs Lisp, and the available operations are
  537. different.  For example, text can be inserted into a buffer very
  538. quickly, while "inserting" text into a string is accomplished by
  539. concatenation and the result is an entirely new string object.
  540.    Each buffer has a designated position called "point" (*note
  541. Positions::.).  And one buffer is the "current buffer".  Most editing
  542. commands act on the contents of the current buffer in the neighborhood
  543. of point.  Many other functions manipulate or test the characters in
  544. the current buffer and much of this manual is devoted to describing
  545. these functions (*note Text::.).
  546.    Several other data structures are associated with each buffer:
  547.    * a local syntax table (*note Syntax Tables::.);
  548.    * a local keymap (*note Keymaps::.); and,
  549.    * a local variable binding list (*note Buffer-Local Variables::.).
  550. The local keymap and variable list contain entries which individually
  551. override global bindings or values.  These are used to customize the
  552. behavior of programs in different buffers, without actually changing the
  553. programs.
  554.    Buffers have no read syntax.  They print in hash notation with the
  555. buffer name.
  556.      (current-buffer)
  557.           => #<buffer objects.texi>
  558. File: elisp,  Node: Window Type,  Next: Frame Type,  Prev: Buffer Type,  Up: Editing Types
  559. Window Type
  560. -----------
  561.    A "window" describes the portion of the terminal screen that Emacs
  562. uses to display a buffer.  Every window has one associated buffer, whose
  563. contents appear in the window.  By contrast, a given buffer may appear
  564. in one window, no window, or several windows.
  565.    Though many windows may exist simultaneously, one window is
  566. designated the "selected window".  This is the window where the cursor
  567. is (usually) displayed when Emacs is ready for a command.  The selected
  568. window usually displays the current buffer, but this is not necessarily
  569. the case.
  570.    Windows are grouped on the screen into frames; each window belongs to
  571. one and only one frame.  *Note Frame Type::.
  572.    Windows have no read syntax.  They print in hash notation, giving the
  573. window number and the name of the buffer being displayed.  The window
  574. numbers exist to identify windows uniquely, since the buffer displayed
  575. in any given window can change frequently.
  576.      (selected-window)
  577.           => #<window 1 on objects.texi>
  578.    *Note Windows::, for a description of the functions that work on
  579. windows.
  580. File: elisp,  Node: Frame Type,  Next: Window Configuration Type,  Prev: Window Type,  Up: Editing Types
  581. Frame Type
  582. ----------
  583.    A FRAME is a rectangle on the screen that contains one or more Emacs
  584. windows.  A frame initially contains a single main window (plus perhaps
  585. a minibuffer window) which you can subdivide vertically or horizontally
  586. into smaller windows.
  587.    Frames have no read syntax.  They print in hash notation, giving the
  588. frame's title, plus its address in core (useful to identify the frame
  589. uniquely).
  590.      (selected-frame)
  591.           => #<frame xemacs@mole.gnu.ai.mit.edu 0xdac80>
  592.    *Note Frames::, for a description of the functions that work on
  593. frames.
  594. File: elisp,  Node: Window Configuration Type,  Next: Marker Type,  Prev: Frame Type,  Up: Editing Types
  595. Window Configuration Type
  596. -------------------------
  597.    A "window configuration" stores information about the positions and
  598. sizes of windows at the time the window configuration is created, so
  599. that the screen layout may be recreated later.
  600.    Window configurations have no read syntax.  They print as
  601. `#<window-configuration>'.  *Note Window Configurations::, for a
  602. description of several functions related to window configurations.
  603. File: elisp,  Node: Marker Type,  Next: Process Type,  Prev: Window Configuration Type,  Up: Editing Types
  604. Marker Type
  605. -----------
  606.    A "marker" denotes a position in a specific buffer.  Markers
  607. therefore have two components: one for the buffer, and one for the
  608. position.  The position value is changed automatically as necessary as
  609. text is inserted into or deleted from the buffer.  This is to ensure
  610. that the marker always points between the same two characters in the
  611. buffer.
  612.    Markers have no read syntax.  They print in hash notation, giving the
  613. current character position and the name of the buffer.
  614.      (point-marker)
  615.           => #<marker at 10779 in objects.texi>
  616.    *Note Markers::, for information on how to test, create, copy, and
  617. move markers.
  618. File: elisp,  Node: Process Type,  Next: Stream Type,  Prev: Marker Type,  Up: Editing Types
  619. Process Type
  620. ------------
  621.    The word "process" means a running program.  Emacs itself runs in a
  622. process of this sort.  However, in Emacs Lisp, a process is a Lisp
  623. object that designates a subprocess created by Emacs process.  External
  624. subprocesses, such as shells, GDB, ftp, and compilers, may be used to
  625. extend the processing capability of Emacs.
  626.    A process takes input from Emacs and returns output to Emacs for
  627. further manipulation.  Both text and signals can be communicated between
  628. Emacs and a subprocess.
  629.    Processes have no read syntax.  They print in hash notation, giving
  630. the name of the process:
  631.      (process-list)
  632.           => (#<process shell>)
  633.    *Note Processes::, for information about functions that create,
  634. delete, return information about, send input or signals to, and receive
  635. output from processes.
  636. File: elisp,  Node: Stream Type,  Next: Keymap Type,  Prev: Process Type,  Up: Editing Types
  637. Stream Type
  638. -----------
  639.    A "stream" is an object that can be used as a source or sink for
  640. characters--either to supply characters for input or to accept them as
  641. output.  Many different types can be used this way: markers, buffers,
  642. strings, and functions.  Most often, input streams (character sources)
  643. obtain characters from the keyboard, a buffer, or a file, and output
  644. streams (character sinks) send characters to a buffer, such as a
  645. `*Help*' buffer, or to the echo area.
  646.    The object `nil', in addition to its other meanings, may be used as
  647. a stream.  It stands for the value of the variable `standard-input' or
  648. `standard-output'.  Also, the object `t' as a stream specifies input
  649. using the minibuffer (*note Minibuffers::.) or output in the echo area
  650. (*note The Echo Area::.).
  651.    Streams have no special printed representation or read syntax, and
  652. print as whatever primitive type they are.
  653.    *Note Streams::, for a description of various functions related to
  654. streams, including various parsing and printing functions.
  655. File: elisp,  Node: Keymap Type,  Next: Syntax Table Type,  Prev: Stream Type,  Up: Editing Types
  656. Keymap Type
  657. -----------
  658.    A "keymap" maps keys typed by the user to functions.  This mapping
  659. controls how the user's command input is executed.  A keymap is actually
  660. a list whose CAR is the symbol `keymap'.
  661.    *Note Keymaps::, for information about creating keymaps, handling
  662. prefix keys, local as well as global keymaps, and changing key bindings.
  663. File: elisp,  Node: Syntax Table Type,  Next: Display Table Type,  Prev: Keymap Type,  Up: Editing Types
  664. Syntax Table Type
  665. -----------------
  666.    A "syntax table" is a vector of 256 integers.  Each element of the
  667. vector defines how one character is interpreted when it appears in a
  668. buffer.  For example, in C mode (*note Major Modes::.), the `+'
  669. character is punctuation, but in Lisp mode it is a valid character in a
  670. symbol.  These different interpretations are effected by changing the
  671. syntax table entry for `+', i.e., at index 43.
  672.    Syntax tables are only used for scanning text in buffers, not for
  673. reading Lisp expressions.  The table the Lisp interpreter uses to read
  674. expressions is built into the Emacs source code and cannot be changed;
  675. thus, to change the list delimiters to be `{' and `}' instead of `('
  676. and `)' would be impossible.
  677.    *Note Syntax Tables::, for details about syntax classes and how to
  678. make and modify syntax tables.
  679. File: elisp,  Node: Display Table Type,  Next: Overlay Type,  Prev: Syntax Table Type,  Up: Editing Types
  680. Display Table Type
  681. ------------------
  682.    A "display table" specifies how to display each character code.
  683. Each buffer and each window can have its own display table.  A display
  684. table is actually a vector of length 261.  *Note Display Tables::.
  685. File: elisp,  Node: Overlay Type,  Prev: Display Table Type,  Up: Editing Types
  686. Overlay Type
  687. ------------
  688.    An "overlay" specifies temporary alteration of the display
  689. appearance of a part of a buffer.  It contains markers delimiting a
  690. range of the buffer, plus a property list (a list whose elements are
  691. alternating property names and values).  Overlays are used to present
  692. parts of the buffer temporarily in a different display style.
  693.    *Note Overlays::, for how to create and use overlays.
  694. File: elisp,  Node: Type Predicates,  Next: Equality Predicates,  Prev: Editing Types,  Up: Types of Lisp Object
  695. Type Predicates
  696. ===============
  697.    The Emacs Lisp interpreter itself does not perform type checking on
  698. the actual arguments passed to functions when they are called.  It could
  699. not do otherwise, since variables in Lisp are not declared to be of a
  700. certain type, as they are in other programming languages.  It is
  701. therefore up to the individual function to test whether each actual
  702. argument belongs to a type that can be used by the function.
  703.    All built-in functions do check the types of their actual arguments
  704. when appropriate and signal a `wrong-type-argument' error if an
  705. argument is of the wrong type.  For example, here is what happens if you
  706. pass an argument to `+' which it cannot handle:
  707.      (+ 2 'a)
  708.           error--> Wrong type argument: integer-or-marker-p, a
  709.    Many functions, called "type predicates", are provided to test
  710. whether an object is a member of a given type.  (Following a convention
  711. of long standing, the names of most Emacs Lisp predicates end in `p'.)
  712.    Here is a table of predefined type predicates, in alphabetical order,
  713. with references to further information.
  714. `atom'
  715.      *note atom: List-related Predicates.
  716. `arrayp'
  717.      *note arrayp: Array Functions.
  718. `bufferp'
  719.      *note bufferp: Buffer Basics.
  720. `byte-code-function-p'
  721.      *note byte-code-function-p: Byte-Code Type.
  722. `case-table-p'
  723.      *note case-table-p: Case Table.
  724. `char-or-string-p'
  725.      *note char-or-string-p: Predicates for Strings.
  726. `commandp'
  727.      *note commandp: Interactive Call.
  728. `consp'
  729.      *note consp: List-related Predicates.
  730. `floatp'
  731.      *note floatp: Predicates on Numbers.
  732. `frame-live-p'
  733.      *note frame-live-p: Deleting Frames.
  734. `framep'
  735.      *note framep: Frames.
  736. `integer-or-marker-p'
  737.      *note integer-or-marker-p: Predicates on Markers.
  738. `integerp'
  739.      *note integerp: Predicates on Numbers.
  740. `keymapp'
  741.      *note keymapp: Creating Keymaps.
  742. `listp'
  743.      *note listp: List-related Predicates.
  744. `markerp'
  745.      *note markerp: Predicates on Markers.
  746. `natnump'
  747.      *note natnump: Predicates on Numbers.
  748. `nlistp'
  749.      *note nlistp: List-related Predicates.
  750. `numberp'
  751.      *note numberp: Predicates on Numbers.
  752. `number-or-marker-p'
  753.      *note number-or-marker-p: Predicates on Markers.
  754. `overlayp'
  755.      *note overlayp: Overlays.
  756. `processp'
  757.      *note processp: Processes.
  758. `sequencep'
  759.      *note sequencep: Sequence Functions.
  760. `stringp'
  761.      *note stringp: Predicates for Strings.
  762. `subrp'
  763.      *note subrp: Function Cells.
  764. `symbolp'
  765.      *note symbolp: Symbols.
  766. `syntax-table-p'
  767.      *note syntax-table-p: Syntax Tables.
  768. `user-variable-p'
  769.      *note user-variable-p: Defining Variables.
  770. `vectorp'
  771.      *note vectorp: Vectors.
  772. `window-configuration-p'
  773.      *note window-configuration-p: Window Configurations.
  774. `window-live-p'
  775.      *note window-live-p: Deleting Windows.
  776. `windowp'
  777.      *note windowp: Basic Windows.
  778. File: elisp,  Node: Equality Predicates,  Prev: Type Predicates,  Up: Types of Lisp Object
  779. Equality Predicates
  780. ===================
  781.    Here we describe two functions that test for equality between any two
  782. objects.  Other functions test equality between objects of specific
  783. types, e.g., strings.  See the appropriate chapter describing the data
  784. type for these predicates.
  785.  - Function: eq OBJECT1 OBJECT2
  786.      This function returns `t' if OBJECT1 and OBJECT2 are the same
  787.      object, `nil' otherwise.  The "same object" means that a change in
  788.      one will be reflected by the same change in the other.
  789.      `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
  790.      value.  Also, since symbol names are normally unique, if the
  791.      arguments are symbols with the same name, they are `eq'.  For
  792.      other types (e.g., lists, vectors, strings), two arguments with
  793.      the same contents or elements are not necessarily `eq' to each
  794.      other: they are `eq' only if they are the same object.
  795.      (The `make-symbol' function returns an uninterned symbol that is
  796.      not interned in the standard `obarray'.  When uninterned symbols
  797.      are in use, symbol names are no longer unique.  Distinct symbols
  798.      with the same name are not `eq'.  *Note Creating Symbols::.)
  799.           (eq 'foo 'foo)
  800.                => t
  801.           
  802.           (eq 456 456)
  803.                => t
  804.           
  805.           (eq "asdf" "asdf")
  806.                => nil
  807.           
  808.           (eq '(1 (2 (3))) '(1 (2 (3))))
  809.                => nil
  810.           
  811.           (eq [(1 2) 3] [(1 2) 3])
  812.                => nil
  813.           
  814.           (eq (point-marker) (point-marker))
  815.                => nil
  816.  - Function: equal OBJECT1 OBJECT2
  817.      This function returns `t' if OBJECT1 and OBJECT2 have equal
  818.      components, `nil' otherwise.  Whereas `eq' tests if its arguments
  819.      are the same object, `equal' looks inside nonidentical arguments
  820.      to see if their elements are the same.  So, if two objects are
  821.      `eq', they are `equal', but the converse is not always true.
  822.           (equal 'foo 'foo)
  823.                => t
  824.           
  825.           (equal 456 456)
  826.                => t
  827.           
  828.           (equal "asdf" "asdf")
  829.                => t
  830.           (eq "asdf" "asdf")
  831.                => nil
  832.           
  833.           (equal '(1 (2 (3))) '(1 (2 (3))))
  834.                => t
  835.           (eq '(1 (2 (3))) '(1 (2 (3))))
  836.                => nil
  837.           
  838.           (equal [(1 2) 3] [(1 2) 3])
  839.                => t
  840.           (eq [(1 2) 3] [(1 2) 3])
  841.                => nil
  842.           
  843.           (equal (point-marker) (point-marker))
  844.                => t
  845.           
  846.           (eq (point-marker) (point-marker))
  847.                => nil
  848.      Comparison of strings is case-sensitive.
  849.           (equal "asdf" "ASDF")
  850.                => nil
  851.    The test for equality is implemented recursively, and circular lists
  852. may therefore cause infinite recursion (leading to an error).
  853. File: elisp,  Node: Numbers,  Next: Strings and Characters,  Prev: Types of Lisp Object,  Up: Top
  854. Numbers
  855. *******
  856.    GNU Emacs supports two numeric data types: "integers" and "floating
  857. point numbers".  Integers are whole numbers such as -3, 0, 7, 13, and
  858. 511.  Their values are exact.  Floating point numbers are numbers with
  859. fractional parts, such as -4.5, 0.0, or 2.71828.  They can also be
  860. expressed in an exponential notation as well: thus, 1.5e2 equals 150;
  861. in this example, `e2' stands for ten to the second power, and is
  862. multiplied by 1.5.  Floating point values are not exact; they have a
  863. fixed, limited amount of precision.
  864.    Support for floating point numbers is a new feature in Emacs 19, and
  865. it is controlled by a separate compilation option, so you may encounter
  866. a site where Emacs does not support them.
  867. * Menu:
  868. * Integer Basics::            Representation and range of integers.
  869. * Float Basics::          Representation and range of floating point.
  870. * Predicates on Numbers::     Testing for numbers.
  871. * Comparison of Numbers::     Equality and inequality predicates.
  872. * Numeric Conversions::          Converting float to integer and vice versa.
  873. * Arithmetic Operations::     How to add, subtract, multiply and divide.
  874. * Bitwise Operations::        Logical and, or, not, shifting.
  875. * Transcendental Functions::  Trig, exponential and logarithmic functions.
  876. * Random Numbers::            Obtaining random integers, predictable or not.
  877. File: elisp,  Node: Integer Basics,  Next: Float Basics,  Up: Numbers
  878. Integer Basics
  879. ==============
  880.    The range of values for an integer depends on the machine.  The
  881. range is -8388608 to 8388607 (24 bits; i.e., -2**23 to 2**23 - 1 ) on
  882. most machines, but on others it is -16777216 to 16777215 (25 bits), or
  883. -33554432 to 33554431 (26 bits).  All of the examples shown below
  884. assume an integer has 24 bits.
  885.    The Lisp reader reads numbers as a sequence of digits with an
  886. optional sign.
  887.       1               ; The integer 1.
  888.      +1               ; Also the integer 1.
  889.      -1               ; The integer -1.
  890.       16777217        ; Also the integer 1, due to overflow.
  891.       0               ; The number 0.
  892.      -0               ; The number 0.
  893.       1.              ; The integer 1.
  894.    To understand how various functions work on integers, especially the
  895. bitwise operators (*note Bitwise Operations::.), it is often helpful to
  896. view the numbers in their binary form.
  897.    In 24 bit binary, the decimal integer 5 looks like this:
  898.      0000 0000  0000 0000  0000 0101
  899. (We have inserted spaces between groups of 4 bits, and two spaces
  900. between groups of 8 bits, to make the binary integer easier to read.)
  901.    The integer -1 looks like this:
  902.      1111 1111  1111 1111  1111 1111
  903. -1 is represented as 24 ones.  (This is called "two's complement"
  904. notation.)
  905.    The negative integer, -5, is creating by subtracting 4 from -1.  In
  906. binary, the decimal integer 4 is 100.  Consequently, -5 looks like this:
  907.      1111 1111  1111 1111  1111 1011
  908.    In this implementation, the largest 24 bit binary integer is the
  909. decimal integer 8,388,607.  In binary, this number looks like this:
  910.      0111 1111  1111 1111  1111 1111
  911.    Since the arithmetic functions do not check whether integers go
  912. outside their range, when you add 1 to 8,388,607, the value is negative
  913. integer -8,388,608:
  914.      (+ 1 8388607)
  915.           => -8388608
  916.           => 1000 0000  0000 0000  0000 0000
  917.    Many of the following functions accept markers for arguments as well
  918. as integers.  (*Note Markers::.)  More precisely, the actual parameters
  919. to such functions may be either integers or markers, which is why we
  920. often give these parameters the name INT-OR-MARKER.  When the actual
  921. parameter is a marker, the position value of the marker is used and the
  922. buffer of the marker is ignored.
  923. File: elisp,  Node: Float Basics,  Next: Predicates on Numbers,  Prev: Integer Basics,  Up: Numbers
  924. Floating Point Basics
  925. =====================
  926.    Emacs version 19 supports floating point numbers, if compiled with
  927. the macro `LISP_FLOAT_TYPE' defined.  The precise range of floating
  928. point numbers is machine-specific; it is the same as the range of the C
  929. data type `double' on the machine in question.
  930.    The printed representation for floating point numbers requires either
  931. a decimal point (with at least one digit following), an exponent, or
  932. both.  For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
  933. are five ways of writing a floating point number whose value is 1500.
  934. They are all equivalent.  You can also use a minus sign to write
  935. negative floating point numbers, as in `-1.0'.
  936.    You can use `logb' to extract the binary exponent of a floating
  937. point number (or estimate the logarithm of an integer):
  938.  - Function: logb NUMBER
  939.      This function returns the binary exponent of NUMBER.  More
  940.      precisely, the value is the logarithm of NUMBER base 2, rounded
  941.      down to an integer.
  942.